Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.
Introduction
Undo under OpenDoc is multi-level and system-wide.
Please note that the ODPart API calls, ReadActionState and WriteActionState are not supported by Undo in OpenDoc 1.0 on the Mac.
Parts
Parts should add undoable actions to the undo history using AddActionToHistory. whichPart identifies your part object, actionData is a reference to your data (a magic cookie), actionType is decribed below. undoActionLabel and redoActionLabel are user-visible strings corresponding to the undo and redo menu items.
void AddActionToHistory(in ODPart whichPart,
in ODActionData actionData,
in ODActionType actionType,
in ODName undoActionLabel,
in ODName redoActionLabel);
Here’s some sample code:
// CREATE UNDO MENU ITEM TEXT
ODIText* undoActionName = CreateIText("Undo My Action");
ODIText* redoActionName = CreateIText("Redo My Action");
The above code illustrates adding a single action to the undo history. Undo makes a copy of the ODActionData and stores it away. To add a transaction to the undo history, such as the drag-moving of some data from one part to a another, parts must use the ODActionTypes, kODBeginAction and kODEndAction.
NOTE: Change in recipe for transactions: The part initiating an action that may span multiple parts should place an action on the stack using the kODBeginAction constant for the ODActionType parameter to AddActionToHistory. When the action is complete, that same part should place the “end” action on the stack using the kODEndAction constant. In between these times, other parts may add single actions to the action history. These actions become part of the entire transaction.
For example, in the case of drag-moving of some data from one part to a another, the source part should add a begin action to the action history, the receiving part should add item(s) to the undo stack about the data received using the kODSingleAction constant, and finally, the source part can close out the transaction by adding an end action to the history.
Another example: in the case of a paste with a link, the destination part should add the begin and end actions to the stack and the source part should add one or more single actions to the undo history.
If the part placing the begin and end actions on the stack notices an error at any point after placing the begin action onto the stack, it should roll back the transaction. Currently there is no clean way to do this other than to clear the entire undohistory. We will mostly likely add a new functionality in the near future to allow for rolling back a transaction.
When an action is undone, ODPart::UndoAction is called for the part that furnished the action. Similarly ODPart::RedoAction is called when an action is redone. When a transaction is undone or redone, every action between the beginning and ending actions, as well as those actions themselves, will be undone or redone.
ODPart::DisposeActionState is called whenever an item on the undo or redo stack is permanently removed. You will be passed a copy of the ODActionData that you originally added with AddActionToHistory. You must take whatever action is relevant to your part. This may be the disposal of any auxiliary data associated with this undo action.
Container applications
Container applications should manage the Undo and Redo menu items and should call Undo and Redo when they are selected. Here's some sample code for the display and activation of these menu items:
ODUndo* undo = MyGetSession()->GetUndo(ev);
ODPart* part;
ODActionData actionData;
ODActionType actionType;
ODName* actionLabel;
// CREATE EMPTY ITEXT STRUCTURE TO BE COPIED INTO
actionLabel = CreateIText(UCHAR_MAX);
// LOOK AT THE STACK
if (undo->PeekUndoHistory(ev, &part, &actionData, &actionType,
